Add a FATES namelist option for land use transition logic by JessicaNeedham · Pull Request #3728 · ESCOMP/CTSM

JessicaNeedham · 2026-01-30T10:42:13Z

Description of changes

This change is coordinated with FATES PR NGEET/fates#1489.
Together they move a hard coded value in FATES, which controls vegetation mortality during transition between land use classes, to a namelist option.

Specific notes

Contributors other than yourself, if any:

CTSM Issues Fixed (include github issue #):

Are answers expected to change (and if so in what way)?
This PR sets the default to option 1 which is different than the current hard coded value of 4. Setting the value to 4 would be equivalent to existing code.

Any User Interface Changes (namelist or namelist defaults changes)?
Yes - see above.

Does this create a need to change or add documentation? Did you do so?
On the FATES side. Not done yet.

Testing performed, if any:
Compiles and runs with NorESM-CTSM-FATES.

NOTE: Be sure to check your coding style against the standard
(https://github.com/ESCOMP/ctsm/wiki/CTSM-coding-guidelines) and review
the list of common problems to watch out for
(https://github.com/ESCOMP/CTSM/wiki/List-of-common-problems).

glemieux

This needs a check in the build namelist to make sure that landuse is not accidentally set off by the user in the namelist. I'll add this check. Otherwise this looks good.

@samsrabin

Change to using the ifx compiler and some more fixes Updates ccs_config to 1.0.75 which has the new ifx compiler in use for derecho_intel, as well as updating to using ESMF8.9.0. This exposed problems in the code on two fronts when running with DEBUG mode: Reliance on short-circuiting in if statements Problems with NaN's, in datasets especially _FillValue For the former, we changed code to break up if statements so this would work. And with the latter we point to new datasets with the NaN's handled. mosart and cdeps code also had short-circuiting problems. @samsrabin created a script to examine all of the files in namelist_defaults_ctsm.xml and in the testmod directories to check if there were problems with NaN's in _FillValues. The modified files here all were the result of the first pass of that script. The new files all have a ".no_nan_fill.nc" ending on them. Includes updating submodules: ccs_config, cdeps, mosart

glemieux · 2026-03-09T22:37:31Z

bld/namelist_files/namelist_defaults_ctsm.xml

+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="1"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="2"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="3"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="4"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="5"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="6"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="7"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="8"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="9"   >.true.</use_fates_luh>


@JessicaNeedham I think we need to remove setting the use_fates_luh to .true. for landuse transition logic setting, since this means by default, full fates will run in landuse mode, which I don't think we want. This would mean that the onus is on the user to set use_fates_luh to true.

Looking at the fates-side of the code, it appears we get the clearing matrix regardless of whether or not use_fates_luh is true (or the ruleset). Does the transition logic setting matter for non-landuse mode? The best I can tell it doesn't since the transition rates are zero in that case. If not, we could create and default to a 0 option for the transition logic that would not turn on landuse mode. We'd just need to add that as a viable case option on the fates side.

cc @ckoven

Thinking about this more, it may be simpler to flip this and make sure that there is a default setting when use_fates_luh is true since this is an option necessary for land use mode. I'll create a PR to this branch @JessicaNeedham.

@glemieux it's sounds like you'll make a PR to this branch, and we need to wait on that to bring this in. Just confirming I have that right.

@glemieux - yes that does sound better. We want it so that if use_fates_luh is true, then this namelist option needs to be set to some default value. I will go ahead and merge your PR - thanks!

glemieux · 2026-03-09T23:06:35Z

FYI, issue to track adding the new namelist option to the FATES user's guide is here: NGEET/fates-users-guide#110

…s true

ekluzek

This is great thanks @JessicaNeedham. I have comments/questions on how best to document this for CTSM users so they have ways of looking up how this works.

There are some things that will need to happen before this comes in. This will come to master as it will include a FATES update, which normally has answer changes that come with it.

@glemieux makes a PR to this one with a change he sees needs to be done
Add in the FATES tag to the .gitmodule file
Resolve conversations
Decide who will do the testing and finalize the tag
Go through the normal testing/tagging process

ekluzek · 2026-03-12T19:42:12Z

bld/namelist_files/namelist_definition_ctsm.xml

+Select the logic for land use class transitions.
+Allowed values are  1-9. See the FATES user guide for an explanation of the options.
+(Only relevant if FATES with land use is on)
+</entry>


It's not currently in the FATES UG. And I didn't see documentation changes in the FATES PR for this (or is the FATES UG located in a different repo?).

The FATES PR does point to Table 1 in this paper:

https://gmd.copernicus.org/articles/13/3203/2020/

which does explain it. So pointing to that table might be the best thing here.

I think you are going for a principle of having the documentation in one place, which is a good goal. It's just that right now that place doesn't exist, so we need a source that can be looked up. It's also easier for users if it is in place and has more visibility. So it's more usable, but less maintainable. But, I also think this is a part that is unlikely to change -- except maybe on a future CMIP cycle. So even though it means duplicating some of this across HLM's the goal of making it easier for users might be OK

Although another thing that could be considered is to tell the user what FATES Fortran code file to look at. Although that's again something that can be changed out from under the documentation here. So I'm not sure the best way of doing this.

I think pointing the user to the FATES user's guide should be the most direct option. I added an issue to the FATES user's guide to make sure we get documentation on this there: NGEET/fates-users-guide#110

ekluzek · 2026-03-12T19:45:25Z

bld/namelist_files/namelist_defaults_ctsm.xml

 <fates_spitfire_mode            use_fates=".true.">0</fates_spitfire_mode>
 <fates_spitfire_mode            use_fates=".true." use_fates_managed_fire=".true." >1</fates_spitfire_mode>
 <fates_harvest_mode             use_fates=".true.">no_harvest</fates_harvest_mode>
+<fates_lu_transition_logic      use_fates=".true.">4</fates_lu_transition_logic>


Since, it's just an integer, it would be good to have a comment to explain that 4 means

"default value of ruleset 4 above means that plants are not cleared during land use change transitions to rangeland, whereas plants are cleared in transitions to pasturelands and croplands."

(taking language from the FATES PR)

Some of the other integer values I find more acceptable, because there's a smaller list, and for example fates_spitfire_mode has a natural progression. This one is more complex and needs an explaination.

ekluzek · 2026-03-12T19:52:33Z

src/main/clm_varctl.F90

                                                                        ! > 1 for external data (lightning and/or anthropogenic ignitions)
                                                                        ! see bld/namelist_files/namelist_definition_clm4_5.xml for details
  logical, public            :: use_fates_managed_fire = .false.        ! true => turn on managed fire
+  integer, public            :: fates_lu_transition_logic = -9          ! controls logic around transition between land use classes 


Does the code check and make sure it was changed from the default value of -9? And that it's within the right range in the Fortran code? The namelist scripts ensure it's between 1 and 9, but the Fortran code should as well.

I've added a check in the CLMBuildNamelist to check for valid values: https://github.com/JessicaNeedham/ctsm/pull/4/changes#diff-c5398a7bf444c79516bff3ba46c0fcc5789d003af843d18b96448d2624d27b18

Is that accomplish what you're thinking about here @ekluzek?

ekluzek · 2026-03-12T19:53:39Z

bld/namelist_files/namelist_defaults_ctsm.xml

+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="1"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="2"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="3"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="4"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="5"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="6"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="7"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="8"   >.true.</use_fates_luh>
+<use_fates_luh                  use_fates=".true." fates_lu_transition_logic="9"   >.true.</use_fates_luh>


@glemieux it's sounds like you'll make a PR to this branch, and we need to wait on that to bring this in. Just confirming I have that right.

ekluzek · 2026-03-12T20:00:38Z

@adrifoster I think this is the PR you mean. This one needs to go to master since it changes answers.

adrifoster · 2026-03-12T21:07:58Z

@adrifoster I think this is the PR you mean. This one needs to go to master since it changes answers.

oh okay...I thought it was B4B but that makes sense!

Add build namelist check for the landuse mode transitional ruleset

Jessica Needham and others added 4 commits October 13, 2025 11:36

add new namelist variable for fates

a5efb18

fix merge error

819a84e

Merge branch 'master' into jfn-fates-nl-lulogic

caa106e

remove 0 option for lu transition namelist

782c977

JessicaNeedham mentioned this pull request Jan 30, 2026

Updates to land use clearing logic NGEET/fates#1489

Open

5 tasks

glemieux self-requested a review January 30, 2026 16:55

update default to match current code

66189be

glemieux approved these changes Mar 9, 2026

View reviewed changes

glemieux requested changes Mar 9, 2026

View reviewed changes

glemieux moved this to Finding Reviewers in FATES Pull Request Planning and Status Mar 9, 2026

glemieux added this to FATES Pull Request Planning and Status Mar 9, 2026

github-project-automation bot moved this from Finding Reviewers to Under Review in FATES Pull Request Planning and Status Mar 9, 2026

glemieux reviewed Mar 9, 2026

View reviewed changes

glemieux mentioned this pull request Mar 9, 2026

Create landuse transition ruleset subsection for the namelist options NGEET/fates-users-guide#110

Open

glemieux added 6 commits March 9, 2026 17:26

minor whitespace change

a8fc8d1

set the default fates lu transition ruleset when fates landuse mode i…

08999a5

…s true

minor whitespace change

ef1ffc8

Add transition logic ruleset check to the landuse mode check

2a838fb

minor whitespace change

72a9074

add fail test for transition logic

3a176e5

ekluzek reviewed Mar 12, 2026

View reviewed changes

ekluzek added enhancement new capability or improved behavior of existing capability science Enhancement to or bug impacting science usability Improve or clarify user-facing options non-bfb Changes answers (incl. adding tests) labels Mar 12, 2026

ekluzek added this to CTSM: Upcoming tags Mar 12, 2026

github-project-automation bot moved this to Ready to start (or start again) in CTSM: Upcoming tags Mar 12, 2026

github-project-automation bot moved this from Ready to start (or start again) to Stalled (needs review, blocked etc.) in CTSM: Upcoming tags Mar 12, 2026

ekluzek added the next this should get some attention in the next week or two. Normally each Thursday SE meeting. label Mar 12, 2026

ekluzek moved this from Stalled (needs review, blocked etc.) to In progress - master in CTSM: Upcoming tags Mar 12, 2026

Merge pull request #4 from glemieux/lulogic-value-check

0e02bcb

Add build namelist check for the landuse mode transitional ruleset

Conversation

JessicaNeedham commented Jan 30, 2026

Description of changes

Specific notes

Uh oh!

glemieux left a comment

Choose a reason for hiding this comment

Uh oh!

glemieux Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glemieux Mar 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glemieux commented Mar 9, 2026

Uh oh!

ekluzek left a comment • edited by glemieux Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glemieux Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ekluzek commented Mar 12, 2026

Uh oh!

adrifoster commented Mar 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

glemieux Mar 9, 2026 •

edited

Loading

glemieux Mar 9, 2026 •

edited

Loading

ekluzek left a comment •

edited by glemieux

Loading

glemieux Mar 12, 2026 •

edited

Loading